Skip to content

fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes - #478

Merged
sohail2721 merged 5 commits into
devfrom
chore/fumadocs-openapi-12-6-5
Nov 17, 2026
Merged

sohail2721 merged 5 commits into
devfrom
chore/fumadocs-openapi-12-6-5

Conversation

@sohail2721

@sohail2721 sohail2721 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Takes fumadocs-openapi from 12.6.0 to 12.6.5. That release fixes points 3 to 6 of apimatic/apimatic-io#2350, which we reported upstream as fuma-nama/fumadocs#3864 and fuma-nama/fumadocs#3865. With it, the playground's sign-in moves to the hand-over Fumadocs added in 12.6.2, which keeps the provider's answer out of page addresses.

12.6.5 is one day old, younger than the seven days minimumReleaseAge asks for. It is merged early by decision: see "Merged before the seven days".

What a portal gets

  • A long field path in the playground stays in its panel (points 4 and 5). The middle crumbs truncate, and Unset / Remove stay in reach.
  • A long unbroken string wraps inside its box (points 3 and 6): in a property card, a security scheme's card, and the field info popover.
  • From 12.6.3, credentials are masked. API keys and tokens are typed into password inputs, and the cURL sample shows a credential as ********.
  • From 12.6.3, the playground's rows look different. An optional field outside the request is a muted row that one click adds; a field's name opens its description.
  • From 12.6.4, the playground and the cURL sample build some requests correctly: path parameter values are percent-encoded, form bodies keep 0, false and empty fields, and cookie parameters are sent as the specification says.
  • A sign-in's answer stays out of page addresses. After a playground sign-in the reader lands back on the endpoint page at its own address; the provider's code or token no longer passes through it. The Google tags therefore load there at once, and a page opened through a link of its own ending in ?state=… loads them too, where it used to wait for the next page.

What changes here

  • package.json: fumadocs-openapi 12.6.5, and lucide-react 1.71.0, the lowest version 12.6.5 accepts, so there is still one copy of it.
  • pnpm-lock.yaml: five packages change (the two above, @scalar/openapi-upgrader 0.4.8, @scalar/openapi-types 0.9.9, and a new @scalar/helpers 0.17.1).
  • pnpm-workspace.yaml: @scalar/json-magic is held at 0.16.1 under fumadocs-openapi. 12.6.5 asks for 0.19, whose floor is Node 22.19, above the CLI's 22.14, so CI's --engine-strict install would refuse it. This is the same hold chokidar and undici already have.
  • usage-tabs.tsx: one comment, which said the cURL sample shows typed credentials.

The sign-in hand-over, in its own commit:

  • oauth-callback.ts, oauth.callback.tsx: the callback page leaves its address, the provider's answer in it, in the tab's session storage, where the playground reads it since 12.6.2, and sends the reader back to the page that started the flow at that page's own address. Until now it sent them back with the answer still in the query or the # part.
  • vendor-tags.ts, analytics.ts, playground.tsx: the tags no longer wait for an answer to leave the address. insertTags() holds back on the callback page alone, and holdsOAuthAnswer() and Analytics.loadTags() are gone.
  • oauth-callback.test.ts: a new test runs Fumadocs' own handler script beside ours and holds both to the same entry in the session and the same page, so a move of that entry upstream fails the test and not a portal.

Apart from that, the template compiles and behaves as before against 12.6.5.

Merged before the seven days

fumadocs-openapi@12.6.5 turns seven days old on 23 Nov 2026 at 11:58 UTC. #472 waited for that day. This PR does not: the decision is to take the fix now.

What that costs until 23 Nov:

  • A full re-resolution fails. pnpm dedupe stops with ERR_PNPM_NO_MATURE_MATCHING_VERSION for fumadocs-openapi@12.6.5. A run that needs one adds fumadocs-openapi@12.6.5 to minimumReleaseAgeExclude for that run only.
  • Nothing else changes. CI installs from the frozen lockfile, which never resolves, and pnpm install and pnpm add work as before.

What speaks for the release:

  • It was published by Fumadocs' GitHub Actions with npm provenance, as 12.6.0 was, and it runs no install scripts.
  • The fix itself is one commit that changes class names in five files, fuma-nama/fumadocs@2419e7c.
  • The whole package was not compared with 12.6.0, and the step also takes in 12.6.1 to 12.6.4, which are three to five days old.
  • The other four new packages turn seven days old on 17 Nov, by 14:46 UTC.

After 23 Nov, pnpm dedupe --check should pass without any exception. That is a check only: nothing in the lockfile needs to change.

The lockfile here was resolved with a temporary minimumReleaseAgeExclude of five exact versions, which is not in this PR.

A risk to know about

Because of the @scalar/json-magic hold, the tests in this repository run json-magic 0.16.1, while an npm install -g of the CLI gets 0.19.1. The CLI loads this package (Fumadocs reads a specification through its magic proxy), and 0.19 rewrote that proxy. The portal tests workflow installs the packed CLI as npm does, so it covers the 0.19 side, but it runs on a push to dev, so only after this merges, and on Node 24. I checked that side by hand before then (below): on Node 24, and on Node 22.14.0, the CLI's floor, which is below the 22.19 that json-magic 0.19 declares.

Checked

  • test/e2e/portal-build.test.ts: 78 passing, with the template's type-check against 12.6.5 among them.
  • test/e2e/portal-serve.test.ts: 6 passing.
  • The portal template's unit tests and the portal type tests: 550 passing.
  • No package in the lockfile is refused on Node 22.14.0 under --engine-strict.
  • I did not run the whole suite locally.

In headless Chrome, on portals built from this branch with a neutral spec:

Problem 12.6.0 12.6.5, as built
Form under the request panel, three levels deep, 827 px wide panel 425 px in a 400 px column 400 px, middle crumbs truncate
Unset hidden, five levels deep, 1142 px wide panel 656 px in a 574 px column, Unset cannot be clicked 574 px, Unset can be clicked
Long inline code in a parameter's description 7 px past the card's edge inside the card
Long string in the field info popover 322 px of text in a 262 px box no overflow
  • A playground sign-in, start to finish, against a stand-in OAuth provider, through the hand-over:
    • The authorization code flow, with PKCE, and the implicit flow both sign in, and a request goes out with each one's token.
    • The reader returns from /oauth/callback to the endpoint page at its own address, the tags load there at once, and the entry the callback left in the session is gone once the playground has read it.
    • The refused case shows the provider's error on the callback page.
    • The callback page loads no tag and reports nothing, with an answer nobody started as well. A link from it loads the tags on the next page.
    • A page opened with ?state=CA loads its tags at once and is reported without the parameter.
  • The build a user gets: the packed CLI installed with npm resolves 12.6.5 with json-magic 0.19.1, undici 8 and chokidar 6. It builds the same portal, and the four measurements above are the same.

The tests above ran again after the hand-over commit. The four measurements, the npm-installed build and the Node 22.14.0 checks below ran before it; that commit changes the sign-in's browser code only.

On Node 22.14.0

The packed CLI, installed by npm running on Node 22.14.0 (the official Windows build), as a customer on the CLI's lowest Node gets it:

  • It installs, with EBADENGINE warnings for @scalar/json-magic@0.19.1, chokidar@6.0.0, undici@8.12.4 and undici@8.12.3. The first and the last are new with this PR: json-magic and the undici it pins.
  • fumadocs-openapi 12.6.5 loads json-magic 0.19.1 there, and its magic proxy follows a reference and a circular one.
  • portal generate builds three portals: the layout reproduction, the OAuth one, and a specification with nested, shared and circular $refs across schemas, parameters, a request body and responses.
  • The output is the same as this repository's install gives (Node 24, json-magic 0.16.1). For two of those projects I compared every page's visible text and the data it is rendered from, the Markdown copies, the llms files and the search documents: 16 pages and 16 other files, none differ.
  • portal serve works: an operation page renders with its nested fields, the playground and the cURL sample, and saving the specification updates the page within two seconds.

Not covered: Node 22.15 to 22.18 one by one, and macOS or Linux on 22.14 with json-magic 0.19.

One thing this turned up that is not from this PR: an npm install resolves zbsearch 4.0.4 where the lockfile, on dev too, has 4.0.2, and the two write the search index differently inside. Its documents are the same.

Pictures

Five levels deep, 1142 px wide: the crumbs truncate and Unset is in reach.

The field path truncated, with Unset in reach

A long inline code in a parameter's description, inside its card:

The inline code wrapped inside the property card

A long token in a security scheme's description, inside the popover:

The long string wrapped inside the field info popover

Not in this PR

  • Session replay markers on the playground dialog. Fumadocs sets none yet, so the template still marks the dialog itself.

After this merges

  • feat(portal): load custom scripts from portal.scripts #477 will conflict with it in two places. That PR passes the listed scripts to insertTags() and edits Analytics.loadTags(), which this one removes. Whichever merges second resolves them: insertTags() keeps its new argument and the callback check, and loadTags() stays removed.
  • apimatic/apimatic-io#2352 and the docs draft describe the old sign-in. They say the tags wait on the page a sign-in returns to, and that a page opened with ?state=… loads no tag. Both lines change with this PR.

Part of apimatic/apimatic-io#2350 (points 3 to 6).

🤖 Generated with Claude Code

Muhammad Sohail and others added 2 commits November 17, 2026 10:17
12.6.5 keeps a long field path in the playground inside its panel, with Unset
and Remove in reach, and wraps long unbroken strings inside property cards and
the field info popover: fuma-nama/fumadocs#3864 and #3865, points 3 to 6 of
apimatic/apimatic-io#2350.

lucide-react moves to 1.71.0, the lowest version 12.6.5 accepts, and pnpm dedupe
leaves one copy of it, of shiki and of @base-ui/react.

12.6.5 asks for @scalar/json-magic 0.19, whose floor is Node 22.19, above the
CLI's 22.14, so CI's `--engine-strict` install would refuse it. It is held at
0.16.1, as chokidar and undici are held, and no package in the lockfile is
refused on Node 22.14.0. Unlike those two the CLI loads it, and 0.19 rewrote its
magic proxy: the tests here run 0.16's, an npm install runs 0.19's.

Resolved with a temporary minimumReleaseAgeExclude of five exact versions, which
is not committed. fumadocs-openapi 12.6.5 turns seven days old on 2026-11-23 at
11:58 UTC; lucide-react 1.71.0, @scalar/openapi-upgrader 0.4.8,
@scalar/helpers 0.17.1 and @scalar/openapi-types 0.9.9 do on 2026-11-17.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…e as asterisks

Since fumadocs-openapi 12.6.3 a code usage shows a typed credential as
`********`. The sample still follows the playground's other edits, so it keeps
the playground's replay markers.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sohail2721
sohail2721 marked this pull request as ready for review November 17, 2026 05:24
Muhammad Sohail and others added 2 commits November 17, 2026 10:49
…Node 22.14

An npm install on Node 22.14.0 warns for @scalar/json-magic 0.19.1 and for the
undici 8.12.3 it pins, not for one package as the comment said.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…b's session

Since fumadocs-openapi 12.6.2 the playground reads a returned sign-in from the
tab's session storage, where Fumadocs' own handler leaves the callback's address.
Our callback page now leaves it there too, and sends the reader back to the page
that started the flow at that page's own address. Until now it sent them back with
the provider's answer still in the query or the `#` part.

So no page but the callback has an answer in its address, and the tags no longer
wait for one to be taken out: `insertTags()` holds back on the callback alone,
`holdsOAuthAnswer()` and `Analytics.loadTags()` are gone, and the playground no
longer calls for the tags. A page opened through a link of its own that ends in
`?state=...` loads its tags at once.

A test runs Fumadocs' handler script beside ours in a stand-in tab and holds both
to the same entry in the session and the same page, so a move of that entry fails
the test and not a portal.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Comment thread pnpm-workspace.yaml
# reads a specification through its magic proxy, which 0.19 rewrote. So the tests here run 0.16's proxy
# and an `npm install -g` runs 0.19's, with two more EBADENGINE warnings on Node 22.14, for it and for
# that undici; the portal tests install the packed CLI as npm does.
'fumadocs-openapi>@scalar/json-magic': ^0.16.1

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI tests @scalar/json-magic 0.16.1, while customers get 0.19.1.

Because of this override, every CI job runs json-magic 0.16.1. An npm install -g of the CLI ignores pnpm overrides and gets 0.19.1. That code runs in two places:

  • in the CLI, where create-page.js and dereference.js call createMagicProxy
  • in the portal's browser bundle, where operation.js and usage-tabs.js import getRaw

I checked that 0.19 is safe on the path we use. fumadocs-openapi imports only createMagicProxy and getRaw from @scalar/json-magic/magic-proxy, and both exist in 0.16 and 0.19. In 0.19.1 the magic-proxy code doesn't load undici; only bundle/plugins/fetch-urls does. So the extra EBADENGINE warnings on Node 22.14 don't affect this path at runtime.

The gap is that nothing automated checks 0.19 before this merges. portal_tests.yml installs the packed CLI the way npm does, but it only runs on push to dev. It also has a workflow_dispatch trigger, so could you:

  1. Run portal_tests.yml on this branch (gh workflow run portal_tests.yml --ref chore/fumadocs-openapi-12-6-5) and link the run here before merging? Then the manual 0.19 checks in the description are backed by CI.
  2. Open an issue to remove this pin, with its condition (the CLI's Node floor reaching 22.19), so it doesn't live only in this comment.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First, an apology: you had already started a run on this branch (44030994779), and my dispatch cancelled it 32 minutes in, because the workflow cancels a run in progress on the same ref. I should have listed the runs first. I restarted one, and it has finished.

The run: https://github.com/apimatic/apimatic-cli/actions/runs/44035040377, on b105d56. The one commit after it changes a comment only.

What it backs. With the packed CLI installed as npm does, so with json-magic 0.19.1, these pass: generate the portal, visual, visual — nav.json, generate the auth portal and generate the petstore portal. So CI now covers 0.19 for building a portal and for the visual baselines.

It is not green, and neither is dev. Your baseline run on dev (44031027356, at 8e394e5) fails the same way. The same 16 tests fail in both runs, with the same messages:

  • artifacts: the petstore llms.txt baseline lacks the listPetVisits line.
  • functional: every auth playground test times out on locator('#nd-page').locator('form').first(). That is the inline playground form, which the suite's main still drives; 12.6 moved the playground into a dialog. Each test waits out its two minutes, so the job runs into its 45-minute limit.

The branch run got two tests further than dev before that limit, the digest test and the petstore servers test, and both stop on the same missing form.

So neither failure comes from this PR, but the playground tests cannot vouch for 0.19, or for anything else in the playground, until the suite is updated. apimatic/v4-test-automation#26 is that update for 12.6; it is open and conflicts with main, and the new field rows of 12.6.3 will likely need the page object changed again.

The issue: apimatic/apimatic-io#2353, with the condition (the Node floor reaching 22.19, in engines.node and in the test matrix) and the steps to take the pin out.

I checked your reading of the code paths and agree. To be exact about the files: createMagicProxy is in utils/document/dereference.js, and getRaw in operation.js, ui/operation/usage-tabs.js, utils/create-page.js, utils/get-example-requests.js and utils/schema.js. In 0.19.1 nothing the magic proxy imports reaches undici; only bundle/plugins/fetch-urls/fetch-public-url.js loads it.

Comment thread portal-template/src/lib/vendor-tags.ts Resolved
…s accepted

The page a sign-in returns to loads its tags at once, while the provider's answer
waits in the tab's session storage until a playground reads it. Tags read the
address, not that storage, so the window is accepted, and the comment on
`insertTags()` now says so, with the case of a page that mounts no playground.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

@sohail2721
sohail2721 merged commit 9a4e6e9 into dev Nov 17, 2026
16 checks passed
sohail2721 pushed a commit that referenced this pull request Nov 17, 2026
dev took fumadocs-openapi 12.6.5 (#478), where a sign-in's answer reaches
the playground through the tab's session storage and no page's address
but the OAuth callback's holds it. insertTags() there holds the Google
tags back on the callback only, and Analytics.loadTags() is gone.

Listed scripts follow the same rule here: none on the callback, and all
on the next page view. They used to wait wherever the address held an
answer, which no page a reader returns to does any more. The test that
held them back at such an address now holds them back on the callback,
and a second one loads them at once on a page whose own link carries a
state parameter.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 2.3.0-beta.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants